---
title: Webhook
description: Recibe webhooks de cualquier servicio configurando un webhook personalizado.
---

import { BlockInfoCard } from "@/components/ui/block-info-card"
import { Image } from '@/components/ui/image'

<BlockInfoCard 
  type="generic_webhook"
  color="#10B981"
/>

<div className="flex justify-center">
  <Image
    src="/static/blocks/webhook.png"
    alt="Configuración del bloque Webhook"
    width={500}
    height={400}
    className="my-6"
  />
</div>

## Descripción general

El bloque Webhook genérico te permite recibir webhooks desde cualquier servicio externo. Este es un disparador flexible que puede manejar cualquier carga útil JSON, lo que lo hace ideal para integrarse con servicios que no tienen un bloque Sim dedicado.

## Uso básico

### Modo de paso simple

Sin definir un formato de entrada, el webhook transmite todo el cuerpo de la solicitud tal como está:

```bash
curl -X POST https://sim.ai/api/webhooks/trigger/{webhook-path} \
  -H "Content-Type: application/json" \
  -H "X-Sim-Secret: your-secret" \
  -d '{
    "message": "Test webhook trigger",
    "data": {
      "key": "value"
    }
  }'
```

Accede a los datos en bloques posteriores usando:
- `<webhook1.message>` → "Test webhook trigger"
- `<webhook1.data.key>` → "value"

### Formato de entrada estructurado (opcional)

Define un esquema de entrada para obtener campos tipados y habilitar funciones avanzadas como cargas de archivos:

**Configuración del formato de entrada:**

```json
[
  { "name": "message", "type": "string" },
  { "name": "priority", "type": "number" },
  { "name": "documents", "type": "files" }
]
```

**Solicitud de webhook:**

```bash
curl -X POST https://sim.ai/api/webhooks/trigger/{webhook-path} \
  -H "Content-Type: application/json" \
  -H "X-Sim-Secret: your-secret" \
  -d '{
    "message": "Invoice submission",
    "priority": 1,
    "documents": [
      {
        "type": "file",
        "data": "data:application/pdf;base64,JVBERi0xLjQK...",
        "name": "invoice.pdf",
        "mime": "application/pdf"
      }
    ]
  }'
```

## Cargas de archivos

### Formatos de archivo compatibles

El webhook admite dos formatos de entrada de archivos:

#### 1. Archivos codificados en Base64
Para cargar contenido de archivos directamente:

```json
{
  "documents": [
    {
      "type": "file",
      "data": "...",
      "name": "screenshot.png",
      "mime": "image/png"
    }
  ]
}
```

- **Tamaño máximo**: 20MB por archivo
- **Formato**: URL de datos estándar con codificación base64
- **Almacenamiento**: Los archivos se cargan en almacenamiento seguro de ejecución

#### 2. Referencias URL
Para pasar URLs de archivos existentes:

```json
{
  "documents": [
    {
      "type": "url",
      "data": "https://example.com/files/document.pdf",
      "name": "document.pdf",
      "mime": "application/pdf"
    }
  ]
}
```

### Acceso a archivos en bloques posteriores

Los archivos se procesan en objetos `UserFile` con las siguientes propiedades:

```typescript
{
  id: string,          // Unique file identifier
  name: string,        // Original filename
  url: string,         // Presigned URL (valid for 5 minutes)
  size: number,        // File size in bytes
  type: string,        // MIME type
  key: string,         // Storage key
  uploadedAt: string,  // ISO timestamp
  expiresAt: string    // ISO timestamp (5 minutes)
}
```

**Acceso en bloques:**
- `<webhook1.documents[0].url>` → URL de descarga
- `<webhook1.documents[0].name>` → "invoice.pdf"
- `<webhook1.documents[0].size>` → 524288
- `<webhook1.documents[0].type>` → "application/pdf"

### Ejemplo completo de carga de archivos

```bash
# Create a base64-encoded file
echo "Hello World" | base64
# SGVsbG8gV29ybGQK

# Send webhook with file
curl -X POST https://sim.ai/api/webhooks/trigger/{webhook-path} \
  -H "Content-Type: application/json" \
  -H "X-Sim-Secret: your-secret" \
  -d '{
    "subject": "Document for review",
    "attachments": [
      {
        "type": "file",
        "data": "data:text/plain;base64,SGVsbG8gV29ybGQK",
        "name": "sample.txt",
        "mime": "text/plain"
      }
    ]
  }'
```

## Autenticación

### Configurar autenticación (opcional)

En la configuración del webhook:
1. Habilitar "Requerir autenticación"
2. Establecer un token secreto
3. Elegir tipo de encabezado:
   - **Encabezado personalizado**: `X-Sim-Secret: your-token`
   - **Autorización Bearer**: `Authorization: Bearer your-token`

### Uso de la autenticación

```bash
# With custom header
curl -X POST https://sim.ai/api/webhooks/trigger/{webhook-path} \
  -H "Content-Type: application/json" \
  -H "X-Sim-Secret: your-secret-token" \
  -d '{"message": "Authenticated request"}'

# With bearer token
curl -X POST https://sim.ai/api/webhooks/trigger/{webhook-path} \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-secret-token" \
  -d '{"message": "Authenticated request"}'
```

## Mejores prácticas

1. **Usar formato de entrada para estructura**: Define un formato de entrada cuando conozcas el esquema esperado. Esto proporciona:
   - Validación de tipo
   - Mejor autocompletado en el editor
   - Capacidades de carga de archivos

2. **Autenticación**: Habilita siempre la autenticación para webhooks en producción para prevenir accesos no autorizados.

3. **Límites de tamaño de archivo**: Mantén los archivos por debajo de 20MB. Para archivos más grandes, usa referencias URL en su lugar.

4. **Caducidad de archivos**: Los archivos descargados tienen URLs con caducidad de 5 minutos. Procésalos rápidamente o almacénalos en otro lugar si los necesitas por más tiempo.

5. **Manejo de errores**: El procesamiento de webhooks es asíncrono. Revisa los registros de ejecución para detectar errores.

6. **Pruebas**: Usa el botón "Probar webhook" en el editor para validar tu configuración antes de implementarla.

## Casos de uso

- **Envíos de formularios**: Recibe datos de formularios personalizados con cargas de archivos
- **Integraciones con terceros**: Conéctate con servicios que envían webhooks (Stripe, GitHub, etc.)
- **Procesamiento de documentos**: Acepta documentos de sistemas externos para procesarlos
- **Notificaciones de eventos**: Recibe datos de eventos de varias fuentes
- **APIs personalizadas**: Construye endpoints de API personalizados para tus aplicaciones

## Notas

- Categoría: `triggers`
- Tipo: `generic_webhook`
- **Soporte de archivos**: disponible a través de la configuración del formato de entrada
- **Tamaño máximo de archivo**: 20MB por archivo
